====== stars Plugin ======

---- plugin ----
description: Show stars for rating, difficulty etc.
author     : Collin “Keeyai” Green
email      : stars at keeyai dot com
type       : Syntax
lastupdate : 2008-10-28
compatible : 2008-05-05+
depends    : 
conflicts  : 
similar    : Skill
tags       : poll

downloadurl: https://trello.com/1/cards/5b02f199a283af4081447b09/attachments/5b02f2c1cc9f2ecc5cf03823/download/stars_1.1.zip
bugtracker : 
sourcerepo : 
donationurl: 

screenshot_img: 
----

===== Overview =====

Stars makes it easy to add a rating/difficulty system represented by a number of stars like 2.5 stars or 3/5 stars, etc. It has a simple markup and can handle whole and half stars.

It started as a different plugin called [[plugin:skill|Skill]], but it needed some changes suggested in the comments, and the author hadn’t done anything with the plugin since 2005 and <del>didn’t respond to any emails</del> wasn't interested in maintaining the plugin. Upgrades from the original plugin include:

  * Star limit (10) by anon and kenc
  * Span instead of div by anon
  * New star images instead of using incompatible transparency styling
  * Added css classes to enable external stylesheets
  * Added the ability to show half stars
  * Packaged to work with the DokuWiki plugin manager

===== Usage =====

Usage: ''%%[stars=num]%%'' where num
  * is a number, e.g.: 5
  * or a ratio((**Note:** Stars automatically limits the number of stars to 10 -- ratios over ten, e.g.: 100/500,  will be reduced, e.g.: 2/10)), e.g.:
    * Examples:
      * show 2 stars:''%%[stars=2]%%''
      * show 3/10 stars: ''%%[stars=3/10]%%''
      * show 4.5/5 stars: ''%%[stars=4.5/5]%%''

===== Screenshots =====

{{ https://trello.com/1/cards/5b02f199a283af4081447b09/attachments/5b02f1cc70a9f6439c84093b/download/stars.png?recache |Stars Screenshot}}

===== Download and Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

  * [[https://trello.com/1/cards/5b02f199a283af4081447b09/attachments/5b02f2c1cc9f2ecc5cf03823/download/stars_1.1.zip|stars_1.1.zip]]

===== Change Log =====

  * v. 1.1 -- 2008-10-28
    * Bug fix for half stars
    * Changing the PNGs to GIFs to help our IE friends
    * Added an attempt at making relative paths that will work no matter how deep the calling page is. 
    * Tweaked the alt text for the span itself to be more informative.

===== Discussion =====

I found a few bugs in your otherwise nice plugin:

  * Images don't load correctly, if the page is not in the document root. Change the links to absolute paths.
  * If a page is rated half stars (eg. 3.5/5), one additional empty star is added. This is solved, if the line 114 (''$i++'') is uncommented.
  * Your star images don't work well with IE (can't handle PNG transparency). Use GIF instead or non-transparent background (or no IE).

Here's a code-snippet with my updates, including improved alt text for the images:

<code php>
function _Stars($d)
{
	$string="";

	// render full stars
	for($i=1; $i<=$d[0]; $i++)
		$string .= '<img class="starimage" src="/lib/plugins/stars/star.png" alt="' . $d[0] . '/' . $d[1] . ' stars"  />';

	// render half star if necessary
	if($i-.5 <= $d[0])
	{
		$string .= '<img class="halfstarimage" src="/lib/plugins/stars/halfstar.png" alt="' . $d[0] . '/' . $d[1] . ' stars"  />';
		$i++;
	} // end if($i-$d[0] > 0)

	for($i;$i<=$d[1];$i++)
		$string .= '<img class="emptystarimage" src="/lib/plugins/stars/emptystar.png" alt="' . $d[0] . '/' . $d[1] . ' stars" />';

	return $string;
} // end function _Stars($d)

</code>

 --- //[[martin.bast@tchibo.de|Martin Bast]] 2008/09/29 15:52//

\\
Thanks Martin. I've made changes addressing the items you brought up. Looking back at the code, I fixed the line 114 problem so it works correctly now. I added alt text to the span, not the images (your way would display '7/10 stars' 10 times in a row if the images didn't load). I also tried to solve the relative path problem for pages nested in deeper directories -- I don't have a wiki set up that way though, so it isn't tested.
\\
 --- // [[keeyai@gmail.com|Collin Green]] 2008/10/28 16:10//

\\
To display correctly the star images just change DOKU_PATH with DOKU_URL in lib/plugins/stars/syntax.php
\\
 --- // [[frank@coblan.it|Frank Contrepois]] 2008/12/30 10:06//

It would be awesome if people could vote how many stars they want to give and the number of stars given would automatically adjust.